Menu 2.1 is the evolution of the well known MenuSet package. Plenty of enhancements have been added, in order to make Menu XCMD the most powerful and easy to use menu external ever used.
Major enhancements are :
• The whole set has been compiled in just one XCMD of 16 Kb (26 Kb for 11
externals before).
• Each item or subitem name is now parsed, in order to remove special
formatting codes. Thus, "<B^257Item!√" is same as "item" for the XCMD.
• Special formatting codes can be used in any command parameter.
• Menu, item, subitem names and Command chars are automatically
capitalized to preserve Human Interface Guidelines
• The syntax has been homogenized in all commands :
Menu <command>,<menu>,<item>,<subitem>
and when an additional param is needed, it is always in second place :
Menu <command>,<special>,<menu>,<item>,<subitem>
So, you need now to specify the whole path for a subitem, the XCMD
doesn't search anymore in menu, then submenu list of items. This allows
now to have many identical subitems in a same menu.
• For any item or subitem param, you can use either its name, or its number.
• Everything has been forecast to prevent suppression of user File menu or
of its Quit item, and any modification out of guidelines of this item.
• Install can now even install the File menu. In this case, it will add all the
supplied items before the quit item.
• Switch accepts now About and Help items that go under the Apple menu.
• Many commands have been added to deal with item command, style, ICON or even SICN.
• Extensive online help is available (you have to get the Result after calling to obtain the help text) :
will return "Type “Menu "?",<command>” to get help on a command"
Typing Menu "?",<command>
will return syntax help for that command.
Typing Menu "="
will return "<error> if any OR <ICON|SICN id> OR <styles list> OR <
shortcut char> OR <menus count>"
• When "*" is allowed anywhere in the syntax, it means either "all" most of the time, or "end" for Insert command.
• The menu definition can now use either return or semi-colon as separator.
• A special hack has been provided to allow SICN inserting using special
formatting chars (like ^xxx for an ICON).
• Menu is fully international, giving the right "File" and "Quit" name when you call Switch.
And, like for MenuSet 1.0 :
• Menu 2.1 remains the only XCMD allowing to remove all HC menus
except Apple, File & Edit menu. The File menu is fully customizable, and
the Edit menu still allows Cut, Copy & Paste.
• Even really powerful, it remains a simple to use as any HyperTalk
statement. You will never have to deal with dummy menu IDs stored in
global variables, just pass the names and it will do it for you.
• Finally, like all of my externals, I will support it and regularly enhance it.
SYNTAX
Menu <command> [<param 1>...,<param N>]
USING
The first command parameter will determine the action of Menu XCMD :
SWITCH
Menu "Switch"[,<About item>[,<help item>]]
Hides all HC menus, leaving only the Apple, File & Edit menus. About & Help items will be placed under the Apple menu, File has only a Quit item and Edit keeps all working clipboard handling items.
Called for the first times, Switch hides the HC menus. Called a second time, it restores the original menuBar.
HINT : Whatever is the wording you choose for About item, HC 1.2.x sends doMenu "About HyperCard...". So do a correct test in your handler.
REMOVE
Menu "Remove",<menu|*>[,<item|*>[,<subitem|*>]]
Removes one or all menus, items of a menu or subitems of a submenu. "*" stands for all when used in place of any parameter.
INSTALL
Menu "Install",<menu def>[…,<menu def>]
Installs one or many (up to ten) user menus in one call. MenuDef can any container or literal string containing :
Changes the wording of any item or subitem. Using a comma separated list as new parameter, you can even add a submenu to any existing item, or with special formatting chars change its style, ICON, etc.
INSERT
Menu "Insert",<new>,<menu>,<before item|*>[,<before subitem|*>]
Inserts a new item in a menu or a new subitem in a submenu. If you use
"*" as a param, the new item will be inserted at the end.
CHECK/UNCHECK
Menu "Check",<menu>,<item|*>[,<subitem|*>]
Menu "Uncheck",<menu>,<item|*>[,<subitem|*>]
Checks or unchecks any item or subitem. "*" stands for all when used in place of any parameter, thus allowing to check all items in one call.
ENABLE/DISABLE
Menu "Enable",<menu>[,<item|*>[,<subitem|*>]]
Menu "Disable",<menu>[,<item|*>[,<subitem|*>]]
Enables or disables a whole menu, or any item or subitem. "*" stands for all when used in place of any parameter, thus allowing to set all items in one call.
FIND
Menu "Find",<item or subitem>
Allow to find in which menu/submenu is any item or subitem. You have to get the Result after calling to obtain a list of matching menus. Each line of the returned comma separated list contains a menu name, sometimes the submenu name and the number of the item in the menu or submenu..
LIST
Menu "List",<menu|*>[,<item|*>[,<*>]]
List returns a list of menus, items or subitems. Depending on the params you pass, List wiil return :
Menu "List","*" ........................... comma separated list of menu names
Menu "List","menu"....................... menuDef of menu (see Install)
Menu "List","menu","*"................ list of items & subitems of menu
Menu "List","menu","item"............ item & list of subitems of submenu
Menu "List","menu","item","*"..... list of subitems of submenu
You have to get the Result after calling to obtain the required list.
HINT : if the first item of the returned menus list is "File", then you already called Switch command.
COUNT
Menu "Count",<menu|*>[,<item|*>[,<*>]]
Count returns the number of user menus, items in a menu or subitems in a submenu. Last param must always be "*". You have to get the Result after calling to obtain the resulting number.
If you ask for the number of menus after have called Switch, the File user menu will be one of the totalized menus.
ISCHECKED/ISENABLED
Menu "IsChecked",<menu>,<item>[,<subitem>]
Menu "IsEnabled",<menu>[,<item>[,<subitem>]]
Returns "true" or "false", allowing to know if the menu, item or subitem is checked or enables. You have to get the Result after calling to obtain the value.
GETCMD/SETCMD
Menu "GetCmd",<menu>,<item>[,<subitem>]
Menu "SetCmd",<Cmd char>,<menu>,<item>[,<subitem>]
Returns or sets the command char of any item or subitem. You have to get the Result after calling GetCmd to obtain the cmd char.
GETICON/SETICON
Menu "GetIcon",<menu>,<item>[,<subitem>]
Menu "SetIcon",<ICON ID>,<menu>,<item>[,<subitem>]
Returns or sets the associated ICON of any item or subitem. ICON ID must be greater than 256 but smaller than 512. You have to get the Result after calling GetIcon to obtain the ICON ID.
GETSTYLE/SETSTYLE
Menu "GetStyle",<menu>,<item>[,<subitem>]
Menu "SetStyle",<style>,<menu>,<item>[,<subitem>]
Returns or sets the style of any item or subitem. You have to get the Result after calling GetStyle to obtain the style string.
Style is a one or many chars string which can contain :
N (Normal), B (Bold), I (Italic), U (Underline), O (Outline), S (Shadow),
C (Condense), E (Extend)
GETSICN/SETSICN
Menu "GetSicn",<menu>,<item>[,<subitem>]
Menu "SetSicn",<SICN ID>,<menu>,<item>[,<subitem>]
Returns or sets the associated SICN of any item or subitem. SICN ID must be greater than 256 but smaller than 512. You have to get the Result after calling GetSicn to obtain the SICN ID.
<New>, <Menu>, <item> and <subitem> parameters are always name strings, but you can even use a number for item (the order in menu) and subitem (the order in submenu). Any of these parameters, except Menu name can use the standard formatting chars recognized by the File Mgr, either at the beginning or at the end of the name string :
^XXX associates an ICON resource to the item
!X puts a mark before the item
<X sets the style of the item (B, I, O, U, S)
NOTE : a bug in the Menu Mgr prevents using <E (extend) and <C
(condense) in the string. Using one of these will cause the
item to be ignored. Rather use SetStyle (see later).
/X associates a command key to the item
( disables the item
and a special hack :
¨XXX associates an SICN resource to the item (¨ = option-u)
ERRORS
Finally, don't worry : the XCMD is really bullet-proof, and numerous errors strings are available in the Result when something goes wrong :
"Error : Menu not found"
"Error : Bad ICON or SICN ID (257 ≤ x ≤ 511)"
"Error : Item not found"
"Error : Subitem not found"
"Error : Missing parameter(s)"
"Error : Useless parameter(s)"
"Error : This item has no submenu"
"Error : File menu cannot be removed"
"Error : Quit item cannot be removed from File menu "
"Error : UserLevel must be ≥ 4"
"Error : Couldn't save current Edit menu"
"Error : No more than 10 user menus"
"Error : Bad menu name in param #x"
"Error : Must call Switch before installing File menu"
"Error : "*" not allowed in Change params"
"Error : No more than one subMenu level"
"Error : "*" not allowed in menu param for Insert"
"Error : "*" not allowed in menu param for Check/Uncheck"
"Error : Quit item of File menu cannot be checked"
"Error : Whole File menu cannot be disabled"
"Error : Quit item of File menu cannot be disabled"
"Error : Out of Memory"
"Error : "*" not allowed in IsEnabled params"
"Error : "*" not allowed in IsChecked params"
"Error : "*" not allowed in Get... params"
"Error : "*" not allowed in Set... params"
"Error : SetCmd not allowed for Quit items of File menu"
"Error : SetCmd not allowed for items having a submenu"
"Error : SetSicn not allowed for items having a submenu"
Free for non-commercial use. Use in commercial software subjected to prior acknowledgement and licensing from the author, reachable at the following network addresses:
/Menu 2.1 (US).rsrc/icl4_-16455.png){kind=link}